<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
    <title>JavaScripTools Manual</title>
    <link rel="stylesheet" type="text/css" href="../../css/style.css">
</head>

<body>
<br>
<h1>JavaScripTools Manual</h1>
<h2>JavaScriptUtil</h2>
<h3>Manipulating options on a select box</h3>
<p>JavaScripTools offers the following functions to manipulate the options
inside a select field.</p>
<p><a href="../api/JavaScriptUtil_functions.html#addOption">addOption</a> and
<a href="../api/JavaScriptUtil_functions.html#addOptions">addOptions</a> 
functions add one or more options.</p>
Examples (assuming a select box named choices):
<pre>//Using the standard Option class
addOption("choices", new Option("Zero", "0"));
//Using an object with text and value properties
addOption("choices", {text:"One", value:"1"});
//Using an object with custom properties
addOption("choices", {description:"One", id:"1"}, "description", "id");
//All 3 options are added
addOptions("choices", [new Option("Two", "2"), new Option("Three", "3"), new Option("Four", "4"));
</pre><br>

<p><a href="../api/JavaScriptUtil_functions.html#setOptions">setOptions</a> 
replaces all existing options with the specified ones.</p>
Examples (assuming a select box named choices):
<pre>//Now 'choices' has only these 2 options, no matter the prior state
setOptions("chosen", [new Option("Ten", "10"), new Option("Twenty", "20")); 
</pre><br>

<p><a href="../api/JavaScriptUtil_functions.html#clearOptions">clearOptions</a> 
removes all existing options.</p>
Examples (assuming a select box named choices):
<pre>clearOptions("chosen"); 
</pre><br>

<p><a href="../api/JavaScriptUtil_functions.html#sortOptions">sortOptions</a> 
sorts all options by text.</p>
Examples (assuming a select box named choices):
<pre>sortOptions("chosen"); 
</pre><br>

<p>Controls called 'shuttle', are two select boxes, one containing
a list of all possible choices and the other only the selected choices. Normally,
there are also 4 buttons: Transfer all from right to left, the selected from right to left,
the selected from left to right and all from left to right.</p>
<p>To allow those operations, there is a special function:
<a href="../api/JavaScriptUtil_functions.html#sortOptions">transferOptions</a></p>
Examples (assuming a select box named choices and another named chosen):
<pre>//Transfer all options from 'choices' to 'chosen' (no sorting)
transferOptions("choices", "chosen", true); 
//Transfer the selected options from 'choices' to 'chosen', sorting by text
transferOptions("choices", "chosen", false, true);
</pre><br>

<br><br>
<hr>
<table width="100%">
    <tr>
        <td width="33%" align="left"><b>Previous:</b><br><a href="JavaScriptUtil_values.html">Retrieving and setting values on form fields and html elements</a></td>
        <td width="34%" align="center"><a href="index.html">Table of Contents</a></td>
        <td width="33%" align="right"><b>Next:</b><br><a href="JavaScriptUtil_caret.html">Manipulating caret and selection on input fields</a></td>
    </tr>
</table>

</body>
</html>
